Add postgresql READ\WRITE routing by Naksen · Pull Request #915 · MultiDirectoryLab/MultiDirectory

Naksen · 2026-01-27T15:48:20Z

Задача 1161

Изменения:

В класс Settings добавлены:
- Второй Engine под реплику.
- Настройки для реплики.
- Настройка для смены режимов single \ replication.
Добавлен EngineRegistry, который включает в себя engine мастера и реплики.
Добавлен класс RoutingSession, отнаследованный от Session. В классе переопределены два метода:
- get_bind - метод, к которому обращается сессия перед выполнением запроса в базу (в момент вызовов .flush(), .execute(), .scalars и т.д.) для получения бинда - Engine или Connection.
- flush - в метод добавлено выставление дополнительного флага _force_master для чтения после записи.
Для LDAP добавлена обработка исключения OperationalError, которое возникает при попытке записи в мастер, когда он не доступен. В этом случае отдаем RESPONSE_TYPE (новый ClassVar для реквестов) нашего запроса со статус кодом LDAPCodes.UNAVAILABLE.
Для API был добавлен препинг мастера для тех роутов, которые выполняют запись в мастер.

Новый flow:

Если выставлен режим single - одна база и для чтения и для записи, то ничего не меняется, RoutingSession не используется.
Если выставлен режим replication - то во время каждого запроса в базу мы в методе get_bind определяем в каком мы сейчас состоянии сессии:
1. Только читаем -> отдаем движок реплики. (Например, случай Search запроса)
2. Что-то записываем -> выставляем флаг _force_master, отдаем движок мастера.
3. Чтение после записи -> хоть и приходит запрос на чтение, флаг _force_master уже выставлен, значит отдаем движок мастера. (Например, случай Modify запроса, мы сначала выполняем запросы поиска в реплику, после этого выполняем flush для новой директории и в дальнейшем чтение в рамках запроса идет только из мастера)

Открытые вопросы

Какой код бросать для веба в случае отвала мастера ? - сейчас 503 код с сообщением.
Что делать при финализации session в ioc ? - там происходит session.commit(). Если нам прилетит Modify запрос во время отвала мастера мы упадем в .handle методе с эксепшеном OperationalError, оно обработается выше в методе _handle_tcp \ _handle_api в base.py и LDAP нормально вернет ответ клиенту со статус кодом LDAPCodes.UNAVAILABLE, но при этом выйдет исключение в ioc.py уже после возвращения ответа клиенту. В целом не влияет на работу, но нужно как-то захендлить.
Что делать с обновлением logon атрибутов ? - в первой версии пока просто suppress.
Нужен ли препинг для LDAP аналогичный API ? - пока не делал.
Предложения по другим реализациям маршрутизации приветствуются.

Copilot

Pull request overview

This PR adds PostgreSQL master-replica read/write routing functionality to support database scalability. The implementation introduces a custom routing session that directs write operations to the master database while allowing read operations to use a replica database.

Changes:

New database routing infrastructure with RoutingSession class that routes database operations between master and replica
Configuration options for single or master-replica database modes
Master database availability checks added to all write API endpoints
Error handling for database unavailability with OperationalError suppression and user-facing error responses

Reviewed changes

Copilot reviewed 30 out of 30 changed files in this pull request and generated 18 comments.

Show a summary per file

File	Description
app/database.py	New file implementing RoutingSession for master-replica routing and engine configuration
app/config.py	Added replica database configuration fields and removed engine property from Settings
app/ioc.py	Modified session factory to support routing mode, removed engine provider
app/api/utils.py	New utility function to check master database availability before write operations
app/multidirectory.py	Updated to use engines dictionary instead of settings.engine
tests/conftest.py	Updated test configuration to use engines dictionary
app/ldap_protocol/ldap_requests/base.py	Added RESPONSE_TYPE class variable and OperationalError handling in request handlers
app/ldap_protocol/ldap_requests/*.py	Added RESPONSE_TYPE class variable to request classes
app/ldap_protocol/ldap_requests/bind.py	Added OperationalError suppression for user login attribute updates
app/ldap_protocol/session_storage/repository.py	Added OperationalError suppression for session key creation
app/api/*/router.py	Added check_master_db dependency to write endpoints

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

app/database.py

app/api/utils.py

app/database.py

app/api/audit/router.py

app/api/utils.py

app/config.py

app/database.py

app/ldap_protocol/ldap_requests/abandon.py

app/db_routing.py

app/api/utils.py

…ous routers

…nations and MFA callback

…replica'

…pdate session handling

…ndencies across routers

…meter

milov-dmitriy · 2026-01-30T12:25:47Z

app/ioc.py

    @provide(scope=Scope.APP)
-    def get_engine(self, settings: Settings) -> AsyncEngine:
-        """Get async engine."""
-        return settings.engine
+    def get_engine_registry(self, settings: Settings) -> EngineRegistry:
+        return EngineRegistry(
+            master_engine=settings.engine,
+            replica_engine=settings.replica_engine,
+        )

    @provide(scope=Scope.APP)
    def get_session_factory(
        self,
-        engine: AsyncEngine,
+        settings: Settings,
+        engine_registry: EngineRegistry,
    ) -> async_sessionmaker[AsyncSession]:
        """Create session factory."""
-        return async_sessionmaker(engine, expire_on_commit=False)
+        if settings.POSTGRES_RW_MODE == "single":
+            return async_sessionmaker(
+                bind=engine_registry.get_master_engine(),
+                expire_on_commit=False,
+            )
+
+        return async_sessionmaker(
+            sync_session_class=RoutingSession,
+            expire_on_commit=False,
+            info={"engine_registry": engine_registry},
+        )


у нас теперь будет 2 кейса работы с бд:

single: читаем из мастера, пишем в мастер

replication: читаем из реплики, пишем в мастер (иногда и читаем из мастера)

но RoutingSession используется только тогда, когда у нас режим replication

я бы предложил всю работу с engine вести через прослойку RoutingSession для "шаблонности". т.е. даже в случае с single режимом мы работаем с RoutingSession, можно попробовать даже так: и для чтения и для записи использовать один и тот же engine

milov-dmitriy · 2026-01-30T12:26:58Z

app/config.py

+        if self.POSTGRES_RW_MODE != "replication":
+            return None


мб тут стоить райзить ошибку?
мы дергаем replica_engine значит это не просто так, значит значение переменной POSTGRES_RW_MODE обязано быть replication иначе дичь какая-то

milov-dmitriy · 2026-01-30T12:27:57Z

app/config.py

    TCP_PACKET_SIZE: int = 1024
    COROUTINES_NUM_PER_CLIENT: int = 3

+    POSTGRES_RW_MODE: Literal["single", "replication"] = "single"


[опционально] это я бы вынес в отдельный тип условно POSTGRES_RW_MODE_TYPE, хотя выглядит как излишнее, но мне просто не нравятся "магические переменные" в коде, хочется их попрятать

milov-dmitriy · 2026-01-30T12:29:21Z

app/api/audit/router.py

+@audit_router.put(
+    "/policy/{policy_id}",
+    error_map=error_map,
+    dependencies=[Depends(require_master_db)],


require_master_db в описании указано что это используется везде где идет запись.. боюсь что мы разработчики можем забывать указывать эту зависимость в будущих роутах, но я не могу придумать как перестраховаться.

может имеет смысл сделать "базовый" роут в котором эта штука есть по умолчанию, внутри этой функции ведь есть защита от "избыточного" препинга когда у нас сингл

а нет, смысла нет, т.к. при реализации мастер мастер этот препинг уйдет

Copilot AI review requested due to automatic review settings January 27, 2026 15:48

Copilot started reviewing on behalf of Naksen January 27, 2026 15:48 View session

Copilot AI reviewed Jan 27, 2026

View reviewed changes

Naksen added 6 commits January 28, 2026 16:29

add: rw database routing

f0cffcd

add: define RESPONSE_TYPE for various LDAP request classes

15a630a

add: handle OperationalError when setting user logon attributes

7fe0ce4

add: implement master database check utility and apply it across vari…

9f1ee6c

…ous routers

test: update get_engine method to use master database engine

ba8a4e6

fix: exclude ABANDON protocol from master DB availability checks

7891162

Naksen force-pushed the add_postgresql_rw_routing branch from 0cbb784 to 7891162 Compare January 28, 2026 13:30

Naksen added 11 commits January 28, 2026 17:01

fix: remove unnecessary dependency on check_master_db for audit desti…

daf3fc0

…nations and MFA callback

fix: handle OperationalError specifically in master DB check

1b35fc3

refactor: format

d03f67e

fix: update POSTGRES_RW_MODE to use 'replication' instead of 'master_…

f516ca6

…replica'

refactor: implement async engine management with EngineRegistry and u…

e6a5323

…pdate session handling

refactor: database module name

d53f18b

refactor: rename check_master_db to require_master_db and update depe…

2d672ba

…ndencies across routers

fix: handle OperationalError by initializing responses to an empty list

40a9ed4

refactor: update _add_app_sqlalchemy_debugger to accept settings para…

40a14a4

…meter

refactor: format

24758c4

fix: add _force_master flag to execute ops

a9d9504

milov-dmitriy reviewed Jan 30, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add postgresql READ\WRITE routing#915

Add postgresql READ\WRITE routing#915
Naksen wants to merge 17 commits intodevfrom
add_postgresql_rw_routing

Naksen commented Jan 27, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

milov-dmitriy Jan 30, 2026

Uh oh!

milov-dmitriy Jan 30, 2026

Uh oh!

milov-dmitriy Jan 30, 2026

Uh oh!

milov-dmitriy Jan 30, 2026

Uh oh!

milov-dmitriy Jan 30, 2026

Uh oh!

milov-dmitriy Jan 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Naksen commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Задача 1161

Изменения:

Новый flow:

Открытые вопросы

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

milov-dmitriy Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

milov-dmitriy Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

milov-dmitriy Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

milov-dmitriy Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

milov-dmitriy Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

milov-dmitriy Jan 30, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Naksen commented Jan 27, 2026 •

edited

Loading